 /*______________________________________________________________________________
 *
 * Copyright 2005 NORSYS
 *
 * Redistribution and use in source and binary forms, with or without
 * modification, are permitted provided that the following conditions
 * are met:
 *
 * (1) Redistributions of source code must retain the above copyright
 *     notice, this list of conditions and the following disclaimer.
 *
 * (2) Redistributions in binary form must reproduce the above copyright
 *     notice, this list of conditions and the following disclaimer in
 *     the documentation and/or other materials provided with the
 *     distribution.
 *
 * (3) The name of the author may not be used to endorse or promote
 *     products derived from this software without specific prior
 *     written permission.
 *
 * THIS SOFTWARE IS PROVIDED BY THE AUTHOR ``AS IS'' AND ANY EXPRESS OR
 * IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED
 * WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
 * ARE DISCLAIMED. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR ANY DIRECT,
 * INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES
 * (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR
 * SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
 * HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT,
 * STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE)
 * ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED
 * OF THE POSSIBILITY OF SUCH DAMAGE.
 *______________________________________________________________________________
 *
 * Created on 26 sept. 2005
 * Author: Arnaud Bailly
 */
package speculoos.core;

import java.util.Map;


/**
 * Base interface for operation on mappers.
 * This is where most of the work is done. Conceptually, a mapper 
 * may be viewed as a function that takes an object as input,
 * does some computation with side-effects in a given environnement,
 * and returns a result as output object. From the point of view
 * of the client, the fact that a mapper encapsulates communication 
 * with persistent storage medium is irrelevant.
 * <p>
 * Execution of method map occurs in a certain <em>environment</em> (eg. a Map)
 * that is made of a global environment provided by the manager this mapper 
 * is part of (see fr.norsys.mapper.manager.Manage and fr.norsys.mapper.manager.Configure) and by a <em>local</em>
 * environment that is passed as the second parameter of method map. The base
 * contract is that variables defined in the local environment
 * have precedence over values defined in the global environment. 
 * </p>
 * <p>
 * It is a resposibility of the map implementor to ensure this contract is
 * enforced with each call to method map.
 * </p>
 * </p>  
 * <ul>
 * <p /> 
 * The base interface is very crude, offering a single generic method. 
 * Implementations are encouraged to provide more strictly typed 
 * methods for doing their business. 
 * 
 * @author nono
 * @version $Id: Mapper.java 259 2006-05-23 10:34:50Z /C=FR/ST=Nord/L=Lille/O=Norsys SA/OU=UE/CN=Arnaud Bailly/emailAddress=abailly@norsys.fr $
 */
public interface Mapper {

	/**
	 * Invoke this mapper's operation.
	 * Although any kind of object may be given to a mapper, depending on
	 * its type and contract, the general requirements of a mapper are
	 * that it must distinguish between <em>atomic</em> and <em>aggregate</em>
	 * values. Any <code>input</code> parameter or <code>return</code>
	 * value that is a subinterface of {@link java.util.Collection} is 
	 * an aggregate value. This is usually restricted to lists and maps.
	 *  
	 *  
	 * @param input input parameter of this mapper
	 * @param param execution <em>environnement</em> for this  mapper invocation.
	 * @return object representing result of executing this mapper.
	 * @throws MapperException if something gets wrong,...
	 */
	Object map(Object input,Map param) throws MapperException;

	/**
	 * Returns a name idenitfying this mapper.
	 * Two mappers may share the same name if they represent the 
	 * same mapping operation.
	 * 
	 * @return name of mapper. May not be null.
	 */
	String getName();
	
}
